A state diagram is a map of an object's life: the situations it can sit in, the occurrences that move it along, and the arrows that connect the two. This page works through all three pieces with worked, clickable examples — no theory without a diagram next to it.
Every arrow on a state diagram can carry up to four pieces of information. Only the event is common — everything else is optional.
Only the event is mandatory. Open --close_door--> Closed is a perfectly valid transition on its own. The guard narrows when it's allowed to fire; the action says what else happens the instant it does.
An arrow with no event at all fires automatically the moment the source state's internal work — its do / activity — finishes. These are called completion transitions, and they're how a diagram expresses "then it just moves on."
A state is a stretch of time during which an object satisfies some condition, waits for something, or runs an activity. Every diagram also needs two special, non-ordinary states to mark where the story starts and ends.
Rounded rectangle, optionally split into a name compartment and an internal-activities compartment listing its entry /, do /, and exit / operations.
A small filled circle. Not a real state the object ever "sits in" — just a marker for where the diagram begins, exactly one per diagram (or per composite state).
A filled circle inside a ring — the "bullseye." Once reached, the object's behavior in that diagram is complete; no event can fire and no transition can leave it.
"Event" covers more than a button press. UML groups every possible trigger into four kinds, and each one is written differently on a transition label.
An asynchronous, named occurrence sent from one object to another — like a raised flag. Written as just the signal's name: cardSwiped.
The receipt of a direct operation call, complete with its parameters. Written like a method signature: unlock(code).
Fires the instant a boolean condition becomes true — no single discrete signal triggers it, the diagram is just watching a value. Written as when(condition).
Fires once a duration has elapsed since entering the state, or at an absolute time. Written as after(duration) or when(date/time).
Three small machines, three different lessons. The first one is live — fire its events and watch the diagram respond.
Lesson: timer_expires cycles the light through three ordinary states, while power_off is available from every one of them but leads only to the final state — after which the button list empties, because a final state accepts no further events.
Lesson: the guard [attempts < 3] vs. [attempts >= 3] splits one event, pin_incorrect, into two different transitions with two different destinations — this is what keeps a diagram deterministic even when the same event can lead two different places.
Lesson: Draft's do / auto_save() is an ongoing activity, not a one-off action — it keeps running the entire time the document sits in Draft, including through repeated trips around the reject loop, and is only cut off once submit finally moves the object out of the state.
Everything above, condensed.
| Term | Meaning |
|---|---|
| State | A condition or situation the object occupies for a stretch of time. |
| Initial pseudostate | Filled dot marking where the diagram begins; not a real state. |
| Final state | Bullseye marking where the object's behavior ends; no outgoing transitions. |
| Event | A significant, instantaneous occurrence that can trigger a transition. |
| Signal event | An asynchronous named occurrence: signalName. |
| Call event | A direct operation invocation: operation(args). |
| Change event | Fires when a boolean condition becomes true: when(condition). |
| Time event | Fires after a duration or at a fixed time: after(duration). |
| Transition | event [guard] / action — the arrow between two states. |
| Guard condition | Boolean check in brackets; the transition can only fire while it holds. |
| Action | Instantaneous, non-interruptible step run when the transition fires. |
| Self-transition | Source and target are the same state; exit and entry actions both re-run. |
| Completion (triggerless) transition | No event listed; fires automatically once the source state's activity finishes. |
| Determinism | At most one transition may be enabled for a given (state, event) pair. |